
 Director
~~~~~~~~~~
Program		Director
Purpose		A Desktop Utility
Version		0.36, 6 September 2003
Author		The RISC OS Director developers,  2003




  Commands file
=================

At the start of each section title is a  character (ALT-164 if your keyboard
doesn't have it) which can be used to search this file.


  Contents
============

 - Contents
 - License
 - Menus
 - Showing a Menu
 - System Variables
 - GSTrans
 - Special forms of Menus and Commands
 - Memoriser
 - MenuMenu
 - Pinboard
 - SaveBox
 - Keys
 - Colours
 - Dynamic Menus
 - Icons
 - Windows
 - Directory Menus
 - Filters
 - Other Commands
 - External Interface
 - SWIs
 - Debugging your Menus
 - Utils
 - Contacts
	

  License
===========

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA


  Menus
=========

Menus are referred to by name (case insensitive), either by the text of the
menu title or an alias as given by you. There can only be one menu of any
given name, and if you attempt to create a menu with the same name as an
existing one then the existing menu will be deleted without warning. This is
useful because you can update your menus at any time you like, or even create
new menus on the fly.

Director keeps a list of menus which you can see from Director's main menu.
Menus can be temporary or permanent. Temporary menus are created by Director
for making Directory Menus and then deleted afterwards. Permanent Menus are
created by you.

To create a menu you need to create an Obey file with the following format.
(Indentation and spacing are generally unimportant. The menus are described
indented here to aid comprehension of the structure.)

	Menu ...
		Option ...
			Command ...
		Option ...
			Command ...
	Dash
		.
		.
		.
		Option ...
	EndMenu

The Menu command signals to Director to start a new Menu with the name and
alias you give it.

Syntax: *Menu
	<title>
	[<alias>]
	[-key <key>]
	[-temp]
	[-remove]

Possible examples are,

	Menu "Mode"
		Starts a menu with title and internal name both "Mode"
	Menu Mode
		Same as above. In general if you want to supply a string
		to a command, you can supply it with or without quotes.
		However if the string has spaces in it it must be supplied
		with quotes.
	Menu "Lots of Modes" Mode
		Starts a menu with title "Lots of Modes" and internal name
		"Mode"
	Menu "DDE" -key ^D
		Starts a menu called DDE with internal name DDE to be opened
		on a CTRL-D key press (see the section called Keys for more
		on what is allowed as a parameter to -keys)
	Menu "Temporary" -temp
		This will make a menu which will be displayed only once and
		then destroyed. This is useful for dynamic menus, and for
		menus displayed with DirectorShowMenu
	Menu "DDE" -remove
		This will remove from director's memory the menu called
		"DDE". This is useful for tidying up. If the menu named
		isn't found then it will not return an error

The EndMenu command signals to Director to stop making the menu. The menu is
available for display as soon as the Menu command has been issued though.

	Syntax: EndMenu [-sort]

If the -sort switch is supplied then Director will sort the menu
alphabetically (case insensitive) by Option. You shouldn't sort menus with
key short cuts.

The Dash command writes a dashed line across the menu at that point in the
menu structure. It is useful for organising large menus.

	Syntax: Dash

The Option command is at the heart of Director's menus. It has many options
which you won't need immediately, but which may become useful later.

	Syntax: Option <text> | -path <file|directory>
		[-tick]
		[-bg <col>]
		[-fg <col>]
		[-sub [<menu>|*]]
		[-len <len> [-allow <characters>]]
		[-dash]
		[-grey]
		[-key <number>]
		[-up]
		[-nosprite]
		[-sprite <name>]

The Option command must be supplied with a text or a path or both. For
example

	Option "Mode 31"
		Will produce a menu entry with the text "Mode 31" which could
		have a command attached (see later).
	Option -path ADFS::4.$.Apps
		Will produce a menu entry with a directory icon in it and the
		Apps directory attached. If the Apps directory is not
		present then it will produce a greyed out menu option with
		an unknown file icon. Director will use the leaf name of
		the path for the text of the menu (in this case Apps) minus
		an initial !.
	Option "Applications" -path ADFS::4.$.Apps
		As above except the text in the menu option will be
		"Applications" rather than "Apps".

A text option may have a 0, 1 or 2 Commands attached (see later) or a
SubMenu.

	Option "Modes" -sub "Modes"
		This produces a menu entry with the text "Modes" and a right
		pointing arrow. When pointer moves over the arrow the Menu
		"Modes" will be opened as a sub menu. If the user clicks on
		the item (or uses a hotkey) the "Modes" menu will be opened
		as the root menu.
	Option "Modes" -sub *
		This is equivalent to the Option above. It is quite common
		to have a SubMenu with the same name as the Option which
		activates it, so this is shorthand for that.

A menu option may be activated by a key, eg

	Option -path ADFS::4.$.Apps -key ^A
		Opens the Apps directory on CTRL-A
	Option "Modes" -sub * -key M
		Opens the modes SubMenu (if no command attached) or does the
		attached command if M is pressed.
	Option "Command" -key ^Z
		If a command is attached then it does it on SHIFT-CTRL-Z
		otherwise it does nothing.

A menu option may have its foreground and background colours defined (see the
section on colours for details of which numbers make which colours). If the
colours are not defined then they default foreground Black and background
White.

	Option "Format" -fg 11
		Produces Red text on the default background
	Option "Boot" -fg 0 -bg 8
		Produces White text on a Dark Blue background

Any menu can be made writable by including a -len option. The parameter to
len is the maximum length of the string writable into the icon. When the
item is selected the text is written into the system variable <MenuText>
which can be used in commands. In fact <MenuText> is written for
non-writable items and when creating a submenu too.

	Option "13" -len 3
		Might be used for typing in a mode number of maximum length 3
		characters. The command attached would then use <MenuText>
		to set the actual mode. The string "13" is the default text.
	Option "" -len 200
		Might be used by a general purpose command (eg the New Task
		option in the TaskManager). The default string is empty.
		It must be supplied though or Director will complain.
	Option "" -len 16 -allow "0-9"
		The allow option lets you specify what characters can be
		typed in. In this case it will only allow the user to type in
		numbers.
	Option "filename" -len 16 -allow "~ "
		This stops the user from typing in a space
		Might be used for typing in the name of a file.

-tick Ticks the menu item (useful for when you have 2 attached commands, this
provides the initial ticked state).

-dash Writes a dash under the menu item. This is equivalent to the Dash
command.

-grey Makes the menu entry grey and unselectable. Useful occasionally.

-up Makes -path have the directories above the path (Up Menus - see Directory
Menus section) in the menu. If -up is applied to a file then it will have a
submenu arrow.

-nosprite Stops a sprite appearing in a -path menu. It also stops the menu
entry being greyed out if the path did not exist.

-sprite adds the named sprite into the menu entry. The sprite must be the
correct size (the same size as small filer icons). If it is not found it is
replaced with a file_xxx sprite (a blank white square).

The Command command is for attaching commands to menu options. Only text
type menu options (ie not -path options) may have Commands attached. You may
have both SubMenus and commands attached to a menu option.

	Syntax: Command <*command>

For example

	Option "Mode 13"
		Command WimpMode 13
			Sets Mode 13 when clicked on
	Option "13" -len 3
		Command WimpMode <MenuText>
			Sets the mode typed in when clicked on
	Option "" -len 200
		Command <MenuText>
			Runs the command typed in when clicked on.

A menu option may have two commands attached. Which command is run depends
upon the ticked state of the option.

For example

	Option "A"
		Command FontInstall Fonts:!A.
		Command FontRemove Fonts:!A.

When this it not ticked then the first command will be run. This will
install the fonts in !A and to show that they have been installed the menu
option will be ticked. To remove the fonts the option is clicked again and
the second command is run, removing the fonts, and returning the menu to the
non-ticked state.

Commands are GSTransed before being run (see the section on GSTrans for more
info) as a WimpTask. Running commands as a WimpTask means that they don't
interfere with Director, however if the command produces an error, an
anonymous error box is produced.

This also means that multiple OS commands can be put on one line by
separating them with |M. For example

	Option "Reset SysFont"
		Command fx 20|MSWI Wimp_CommandWindow -1

Which resets the system font with *FX 20 and then redraws the screen with the
SWI Wimp_CommandWindow.


  Showing a Menu
==================

A menu can be shown immediately with the command

	DirectorShowMenu <menu_name>

This will open the menu named immediately. You can make obey files which
define menus and then open them immediately with this command. If you add
-temp to the menu then it will be deleted after it has been shown.


  System Variables
====================

These system variables are set whenever a path sub menu is opened or a path
item is chosen

	Director$CurrentPath
		full path of object
	Director$CurrentDir
		directory object lives in
	Director$CurrentLeaf
		leaf name of object

If the object is a root directory (eg ADFS::4.$ or Root:) then CurrentPath =
CurrentDir = CurrentLeaf


The last Command that was run can be seen in the system variable

	Alias$DirectorRun

So issue *Show Alias$DirectorRun at the command line to see what it was.


Whenever a text option is chosen

	MenuText

Is set to the text of that option


Whenever menu is clicked over the File 'xxx' option in a Filer Menu

	Leaf

is set to the leaf name of the file ("xxx" in this case).

When Director quits it looks though any system variables of the form

	Director$AtExit*
	
and runs the associated text as a command. This is useful for setting Director
to do something on shutdown or when Director is killed.

(Technical note: these commands won't get run if you restart Director while
it is running. This is because Director isn't running as a task when it is
killed (and can't do) so it can't launch the commands as tasks. If anyone
feels strongly about this then I might change it.)


  GSTrans
===========

If you are uncertain what GSTrans is, look it up in the index of your user
guide. The few pages referenced will teach you the basics (I won't attempt
to explain them here).

As a rule every string parameter passed to Director is GSTransed when it is
parsed. This means that

	Option -path <Wimp$Scrap>

Will be GSTransed into (something like)

	Option -path ADFS::HardDisc4.$.!Boot.!Scrap.ScrapDirs.ScrapFile

Which means that if Wimp$Scrap changes, the option won't be looking in the
right place. The menu text will read "ScrapFile". Better is

	Option -path |<Wimp$Scrap>

Which GSTranses into

	Option -path <Wimp$Scrap>

which is what you want. The menu text will read "<Wimp$Scrap>". Probably
best (for this use) is

	Option "Scrap" -path |<Wimp$Scrap>

Which has the menu text "Scrap" but is otherwise identical to the one above.

The only strings which don't get GSTransed on their way into Director are the
parameters to Command. These are GSTransed just before being run.

	Option "13" -len 3
		Command WimpMode <MenuText>

The above command will only be GSTransed when it is run with the actual value
of MenuText, not the value of MenuText when the command was installed.

	Option "Open App"
		Command Filer_OpenDir <Obey$Dir>
	Option "Open App"
		Command Filer_OpenDir |<Obey$Dir>

These two commands in practice do the same thing. This is because in the
first Command the <Obey$Dir> is GSTransed (when the Command is being
prepared) to the proper path which is then passed to Filer_OpenDir. In the
second case |<Obey$Dir> is GSTransed to <Obey$Dir> and passed to
Filer_OpenDir. Filer_OpenDir GSTranses the argument and comes up with the
same answer.

If the commands had been Filer_Run in the above example then they would have
done two different things. The first would have worked (running the
application) and the second would not because Filer_Run does not GSTrans its
input. (In fact the second command would have opened a directory onto the
application for some obscure reason, with the Filer title set to <Obey$Dir>
which should not normally be allowed.)


  Special forms of Menus and Commands
=======================================

Whenever a Menu, SubMenu or Command is specified it may take one of several
special forms. These enable Director to be much more general, running
commands instead of opening a sub menu or vice versa. It also means that
Commands can be attached to clicks on icons as well as menus.

When a Menu, SubMenu or Command is being processed, it is first checked to
see if it is prefixed in one of the ways below. If it is then its action is
modified.

"Text"		For normal command or sub-menu (ie action unchanged)

"Menu:Name"	To bring up named menu

"Save:Path"	For save box of the given Path (*)

"Path:Path"	For a directory menu of that Path (*)

"Command:Text"	Runs the Text as if it were a command

"Quit:"		Quits Director

"Info:"		Brings up Director's info window

"OldMenu:"	To open the last filtered menu (for getting pinboard menu)

"MenuMenu:Path"	Takes Path, adds .<leaf> to it and opens the MenuMenu
		pointing at that file. Used internally. (*)

"Memoriser:"	Opens a menu of recently used files.
		(See Memoriser section.)

"Dynamic:Text"	Runs the Text as if it were a command. When the command
		returns Director tries to open the menu whose name is in
		the system variable Director$Menu.

"GSTrans:Text"	GSTranses the Text and then reinterprets it as an extended
		command.

(*) If the path is missing eg "Path:" or "Save:" then it will use the path of
the window that the pointer is over. If the path is present it is GS_Transed
before use.

For example

	Option "Floppy" -sub "Path:ADFS::0.$"

This will make a directory menu of the floppy disc drive if you click on the
option or move the pointer over the SubMenu. This is better than

	Option "Floppy" -path ADFS::0.$

because this will produce a greyed out path with an unknown file icon if the
floppy is empty when the Option is run.

	Option "Root" -sub "Command:Filer_OpenDir ADFS::4.$"

This will open a filer window of your root directory if you click on the
option or move the pointer over the SubMenu.

	Option "Pinboard" -sub "OldMenu:"

This will open the menu that should have been opened when you clicked the
pointer. So if you opened the menu over the pinboard, but wanted to see the
pinboard menu then you could click or slide this option.

	Option Here -sub "Path:<Director$CurrentDir>"
	Option Copy -sub "Save:<Director$CurrentPath>"

These options are useful for the MenuMenu (see the section titled MenuMenu
and the section titled SaveBox).

	Option Info -sub Info:
	Option Quit
		Command Quit:

Helps bring an air of normality to Director by providing the standard Quit
and Info choices!


  Memoriser
=============

Director notices whenever you load a file or click on a drive and keeps a
record of the fact.

If you then ask for the menu Memoriser: to be opened then you will get a menu
with these files or directories in it.

This acts exactly like a normal directory Menu, except it has all your most
recently used files/directories in it.

This is exceedingly useful when you traverse a large directory tree, open a
file to have a look at it, close it, and then realise that you want to see
the file again. All you have to do is open the Memoriser menu and it will be
there sitting at the top. If in the mean time you have deleted the file then
it will not be shown in the menu.

It is possible to make the memoriser display only applications, directories
or files by adding a numeric parameter after the Memoriser:

	Memoriser:1 - memoriser shows applications
	Memoriser:2 - memoriser shows directories and images
	Memoriser:4 - memoriser shows files

The parameters can be combined in a linear fashion, eg Memoriser:6 shows
directories, images and applications but not files.

The total number of items that are kept in the Memoriser menu is definable
with the command

	Syntax: MemoriserItems <number>

If you set it to 0 then you won't get any items in the menu, effectively
turning the feature off. 0 is the default value.

You can save and restore the memoriser with

	MemoriserSave <file>
	MemoriserLoad <file>

This will save the contents of the memoriser or replace it with that in the
file. The file is a simple text file with a file path on each line. The
file at the top of the menu appears at the bottom of the file.

You can clear the memoriser with

	MemoriserClear

By default Director saves and restores the memoriser settings to the file
<Director$Write>.Memoriser on startup and shutdown. You could also use
MemoriserLoad to prime the memoriser with often used files.


  MenuMenu
============

A menu with name defined by the system variable Director$MenuMenu (defined by
you) is opened whenever you click Menu on a path item or click Menu on the
second option in a Filer Menu (the one that reads "File '!Run'" or
"Selection") provided one and only one file is selected in the Filer window.

This menu deals with files and directories. You should put on it things
which you want to do to files.

Here is an example of a MenuMenu

Set Director$MenuMenu MenuMenu

Menu "FileMenu" "MenuMenu"
	Option Here -sub "Path:|<Director$CurrentDir>"

This allows you to see a directory Menu of where the selected file or
directory is. (See the section on GSTrans for the reason behind the | in the
-sub string.)

	Option Copy -sub "Save:|<Director$CurrentPath>"

This allows the current file or directory to be copied to a filer window,
dragged to an application or pinned to the pinboard (drag the icon onto the
pinboard).

	Option "Set CSD"
		Command Dir <Director$CurrentDir>

Sets the Current Directory to the directory in which the file or directory
was found.

	Option "Open Directory"
		Command Filer_OpenDir <Director$CurrentDir>

This opens a Filer Window onto the directory in which the file or directory
was found.

	Option "Filer_Run"
		Command Filer_Run <Director$CurrentPath>

This is equivalent to double clicking on the File or Directory.

	Option "Pin"
		Command SWI OS_Mouse TO x y|M
			Pin <Director$CurrentPath> |<x>-90 |<y>+45

This pins the file or Directory to the pinboard. (The command should be
written all on one line). It uses the SWI Module to read the current
position of the mouse and then pins the centre of the icon there. (Note the
|<x>, this is GSTransed to at run time <x> when the Command is being
prepared, which is then GSTransed to the mouse x co-ordinate when the Pin
command is run.)

	Option "IconSprites"
		Command IconSprites <Director$CurrentPath>

This IconSprites the file or directory. (Only really useful over a sprite
file.)

EndMenu

There are many other possibilities for the MenuMenu, such as SetType,
ToolSprites, Delete, Wipe, Access etc. A MenuMenu is perhaps best defined as
a dynamic Menu.


  Pinboard
============

A menu of this name (defined by you) is opened whenever you click Menu on the
pinboard backdrop or on a TinyDirs icon.

If the pinboard module isn't loaded or running, no error is produced, but
none of the things in this section will work.

If you want to use the Pinboard's menu then you can press any of SHIFT, CTRL,
ALT when clicking Menu and the old Menu will appear.

Alternatively on your Pinboard menu you can have an option

	Option Pinboard -sub OldMenu:

Which when clicked on or slid over will open the menu that would have been
opened if Pinboard had been left to its own devices. It will also move the
pointer to be in the correct place.

(I debated long and hard about moving the pointer (which I dislike), but
decided this was the least confusing option. Try it for yourself!)


  SaveBox
===========

Read the section on special forms of Menus and commands if you haven't
already done so.

The SaveBox is not like a true SaveBox it is more like a miniature Filer
window (except you can't (yet) double click on the icon).

You may drag the icon from a SaveBox to an application (equivalent to
dragging it from the Filer) the pinboard (ditto) or a Filer window, which
will copy the File in the way you have configured (possibly bringing up a
Filer Action window etc).

You may also drag files to the SaveBox from the pinboard or Filer and it will
update to show the file you dragged.

There is only one SaveBox and if you try to open it twice the first one
disappears/changes into the new file/directory.


  Keys
========

Any Menu or Menu Option can have a hot key assigned.

A hot key assigned to a menu (in the Menu command) will open the Menu when
used and a hot key assigned to a Menu Option will be equivalent to clicking
with select on a Menu Option when used.

Keys are added by name and possibly with a modifier.

A single letter key refers to that key eg -key M or -key 8. Keys are case
insensitive (and independent of CapsLock) so -key m is equivalent to -key M.

Some keys are referred to by name (case insensitive), and these are

	Home, Return, Ret, Enter, Backspace, BkSp, Space, Delete,
	Del, Esc, Print, Pnt, F1, F2, F3, F4, F5, F6, F7, F8, F9,
	Tab, Copy, Cpy, End, Left, Right, Down, Up, PageDown, PgDn,
	PageUp, PgUp, F10, F11, F12, Insert, Ins

Some of them are named twice for your convenience. So -key F1, -key f1 or
-Key Insert would be valid.

Possible modifiers are

		SHIFT
	^ 	CTRL
	~ 	ALT

(To get the  symbol, hold down ALT, type 139 on the numeric keypad and
release ALT. Alternatively map character 139 to a key in your favourite
editor (CTRL-6 is a good mapping).)

These can be added (in any order) before a key name, indicating that you have
to press the modifier keys indicated with the main key in order to activate
the hot key. eg

	^M		CTRL-M
	A		SHIFT-A
	^F1 = ^F1	SHIFT-CTRL-F1

Note that -key A = -key a which is not equal to -key A = -key a.

Some key combinations don't work, eg

	CTRL Number keys don't work, CTRL KeyPad numbers should
	No keys work with ALT!

These may be fixed in a future release!

If an Option or a Menu has a key definition it is added to the text/title
with a space before it. If you want the items to line up then you will have
to add spaces after the text/title. RISCOS 3.5 will line them up for you
provided the key definitions starts with ^ or  or is one of the long form
named keys above.


  Colours
===========

Any colours in Director are specified numerically from the 16 Wimp colours.
These colours can be seen by clicking on the Palette icon (supplied with
versions of RISCOS < 3.5). The numbers of each colour are given below.

White	0	Grey4	4	Blue	8	Cream	12
Grey1	1	Grey5	5	Yellow	9	Khaki	13
Grey2	2	Grey6	6	Green	10	Orange	14
Grey3	3	Black	7	Red	11	Cyan	15

These names are defined in the file Director:Library.!Core and are defined by
default so you may use "Director$" + colour name wherever a colour is needed,
eg

	Option "Unreadable" -bg <Director$Red> -fg <Director$Khaki>


  Dynamic Menus
=================

These are menus that are created just before the menu is opened rather than
when you run Director.

They are used from an extended menu "Dynamic:Filename". When this command is
run the file or command "Filename" is run. When the command or file finishes
executing Director will try to open the menu whose name is in the system
variable Director$Menu.

A simple example of a dynamic menu would be this

	Option "Time" -sub "Dynamic:DirectorObey Director:Menus.Time"

This will run the command "DirectorObey Director:Menus.Time" when this menu
option is run. The contents this file might be

	Menu "" Time -temp
		Option "**TheTimeWas**" -fg 11
		Option "<Sys$Time>"
		Option "<Sys$Date><Sys$Year>"
	EndMenu

	Set Director$Menu Time

This creates a temporary menu called Time with the current time and date in
it and returns the string "Time" in Director$Menu for Director to use as the
name of a menu to open.

Because the menu was created as a temporary menu it will be deleted once it
has been displayed to conserve memory (since it is rebuilt each time it is
needed).

Dynamic menus are very useful for displaying lists of things that could vary
whilst Director is running (such as modules or filetypes). A few examples of
dynamic menus are provided in the Menus directory inside Director.

It would be possible to simulate most of the other features of Director using
dynamic menus, however in their current implementation they require a disc
access per use. It would be possible to register the dynamic menu files in
the resource filing system to avoid this and maybe a future version of
Director will do this for you.

Dynamic menus set Director$Window and Director$Icon to the window handle and
icon number that the request was over respectively. This is useful for more
advanced menus like the CloseBox menu example.


  Icons
=========

Icons are created in a similar way to menus. Each one must be named (case
insensitive) by its sprite name or an alias name provided by you and there
can only be one of each name. If you create an icon with the name of an
already existing one then the existing icon will be deleted without warning
and the new one created.

You may attach menus for Select, Adjust and Menu for the icon. Remember that
the menus can also be commands (see the section on Special forms of Menus and
Commands)

This creates a new icon bar icon with attached menus. The icon is referred to
by the name of its sprite or the alias name if supplied.

Syntax: *DirectorIcon
	<sprite>
		Name of the sprite, must be provided and exist in the
		Wimp sprite pool
	[-alias <name>]
		Internal name of the Icon. If this is not supplied
		then the icon is referred to by its sprite name.
	[-text <text>]
		Text to go under the Icon. Optional. If the -time
		option is used then this Text defines the length of
		the time string.
	[-left|-right]
		Whether the icon goes on the left of the Icon bar or
		the right. If omitted will default to -left.
	[-priority <priority>]
		This controls the positioning of the icon. Larger
		numbers are to the outside of the icon bar. Range
		from 0 (inside) - &7FFFFFFF (outside). Experiment to
		see where your icons gets placed or look at 3-98 in
		the RISCOS 3 PRMs.
	[-time <format> | -free <drive spec> | -freemem]
		This makes the text under the icon display a piece of
		information about the system. The
		length of the time is set by the -text option which must be
		given a string which is as long as the longest time string,
		and preferably of the same format
		-time <format>
			This makes the text under the icon display the current
			time, which is updated once per second. The usual time
			format is %24:%mi and it is recomended that the text
			option is "00:00". See the Applications Guide, under
			!Alarm, "Time and date formats" for more details or
			the RISCOS 3 PRMs 1-402.
		-free <drive spec>
			This makes the text under the icon display the free
			space left on a drive. 'Drive spec' can be in the
			format of 'ADFS::4.$' or 'ADFS::HardDisc4'. This
			facility does not work on removable drives.
			The routine uses an internal algorythm to convert the
			free space into a human readable form. This may result
			in a slightly different value to what is displayed by
			the Free space windows.
		-freemem
			This makes the text under the icon display the free
			memory on the machine.
	[-menu <menu>]
	[-select <menu>]
	[-adjust <menu>]
		These allow you to attach menus or commands to the 3 mouse
		buttons.
	[-dragto <menu>]
		This specifies a menu to be run when a file is dragged onto the
		icon. The path of the object dragged can be found from
		Director$CurrentPath Leaf and Dir.
	[-dragfrom <path>|*<menu>]
		This either takes a path which then acts exactly like the
		SaveBox or takes a menu preceded by * which will be run with
		Director$CurrentPath Leaf and Dir set up.
	[-remove]
		If this is specified then the named icon is removed rather than
		created.

For example (these should be typed in on 1 line, but have been split for
clarity)

	DirectorIcon romapps Apps -left -priority &50000000
		-menu "Path:Resources:$"
		-select "Command:Filer_OpenDir Resources:$.Apps"
		-adjust Pinboard

This provides a replacement Apps icon which has the Pinboard menu on Adjust,
does the normal thing on select, and on menu (which would normally say
"Open$") produce a directory menu of the whole of Resources which is usually
much more useful.

	DirectorIcon !Director "00:00:00" -left -priority &0E000000
		-menu IconMenu
		-select IconClick
		-adjust Pinboard
		-time <37>24:%MI:%SE

This produces an icon with Director's own icon, the current time in 24 hour
format and 3 menus, IconClick, IconMenu and Pinboard.

[NB <37> GSTranses to %. This odd looking construction is necessary because
%2 refers to the second argument supplied (when Obeying the file, not in
DirectorObey). Since no arguments were supplied then the time string is
converted to 4:%MI:%SE which is not what was required! <37> is used rather
than %% so the file will work with Obey and DirectorObey]

	DirectorIcon trashcan -left
		-dragto "Command:Wipe |<Director$CurrentPath> ~CFR~V"

This will create a trash can icon which will delete all the items dragged
onto it.

	DirectorIcon directory -left
		-dragfrom "*Command:Dir |<Director$CurrentPath>"

This when you drag the directory icon from the icon bar to a filer window
then it will set the current directory.

	DirectorIcon file_fff Text
		-select "Filer_Run $.Text"
		-dragfrom "$.Text"

This will make an icon which works quite like a TinyDir but for one file
$.Text. You can drag the icon to copy the file or put it into a document and
click on the icon to run the file (in the case of a text file load it into a
text editor).

	DirectorIcon ramfs -free Ram::RamDisc0.$ -text "0000k"
		-priority &40000000
		-select "Command:Filer_OpenDir Ram::RamDisc0.$"
		-adjust "Command:Filer_OpenDir Ram::RamDisc0.$"

Director is now able show the free space left on a drive.

	DirectorIcon !configure -freemem -text "0000k"
		-right -priority &20000000

Director can also show the free memory available


  Windows
===================

Windows are created in a similar way to both menus and icons. Each one must be
named (case insensitive) by its window name or an alias name provided by you
and there can only be one of each name. If you create a window with the name
of an already existing one then the existing window will be deleted without
warning and the new one created.

In order for Director to fully implement windows it needs the help of a
supporting program. This program will get informed of all events which happen
to the window and it decides which one(s) it responds to.

This creates a new window. The window is referred to by the name in the
template file or the alias name if supplied.

	Syntax:	*DirectorWindow
		<template_name>
			Name of the window which must be provided. It must 			exist in the template file specified.
		[-alias <name>]
			Internal name of the window. If this is not supplied
			then the window is referred to by its name.
		[-file <template_file>]
			Template file containing definition for the named
			window.
		[-command <program>]
			This is full filename of the support program which lets 			the window react to key presses and mouse clicks
		[-callevery <seconds>]
			This repeatedly calls the support program every
			<seconds> seconds.
		[-background]
			Keep polling the window even when it's closed.
		[-temp]
			Once closed, the window is removed.
		[-remove]
			If this is specified then the named window is removed
			rather than created.

For example (these should be typed in on 1 line, but have been split for
clarity)

	DirectorWindow Info -alias DirectorInfo
		-file <Director$Resources>Templates
		-command <Director$Dir>.Menus.Internal.Templates

This command setups up the Info window as displayed by Director. This loads
the window Info from the template file <Director$Resources>Templates . The
support program is <Director$Dir>.Menus.Internal.Templates which setups up the
window and handle clicks on the buttons: Web, Email and Help.


  Directory Menus
===================

Directory menus are automatically created and destroyed by Director when you
click with Menu on the title bar of a Filer or other window with a valid path
in it (eg an Edit window) in the default set up. They are also produced by
-path "directory" or Command "Path:Directory" etc.

A menu will appear with all the files that are in the directory in it. It is
intended to be complementary to the Filer, quicker to use, but not as
powerful. The entries are sorted by name.

Each item in the menu has the name of a file or directory and its icon. This
is very similar to a filer window with sort by name, small icons and adjusted
to be tall and thin.

Items in the menu that are directories (or image files) will have a SubMenu
arrow by them. You may traverse this arrow to see the next directory down.

Clicking with Select or Adjust is equivalent to double clicking the file in a
filer window.

Clicking with Menu over an Item will bring up the MenuMenu (see that section
for more details). If a MenuMenu is not defined then it will do nothing.

Directory menus come in 2 flavours, with and without "Up Menus". Up Menus
are the directories above the dotted line. These show the directories up to
the root from where you are now. The first item above the dotted line has
the Menu Menu as a sub-menu (its contents are always visible below the
dotted line).

A directory menu made by "Path:" has Up Menus (eg the ones produced by
clicking Menu over a title bar). A directory menu made by -path does not
have Up Menus by default unless you use the -up switch.


  Filters
===========

Filters are a powerful way to change the appearance of your desktop. You may
add new menus or commands to existing desktop features without having to
patch anything. For instance you could add a new menu onto the task switcher
icon or cause menu over any close icon to come up with a menu.

Filters are referred to by name (case insensitive) as supplied in the
command. There can only be one filter of any given name, and if you attempt
to create a filter with the same name as an existing one then the existing
filter will be deleted without warning.

	DirectorFilter <name> <task> <menu>
		[-icon <n>]
		[-select] [-menu] [-adjust]
		[-shift] [-ctrl] [-alt]
		[-remove]

<name> is the name of the filter to be defined

<task> is the name of the task to filter on or * for all tasks. This task
does not not have to be running when the command is executed and director
will keep track of the task if it is shut down and re-started.

<menu> is the menu (or command) to be executed by the filter

-icon <n> defines an icon number for the filter to execute. If this number
is >= 0 then it will define a normal icon (load the template of the window
you are interested in into a template editor to discover the icon number or
use trial and error). The file Director:Menus.Aliases contains names for a
number special icons which are probably more useful

WorkArea		- background of a window with no icons
BackIcon		- back icon in the top left of a window
CloseIcon		- close icon in the top left of a window
TitleBar		- title bar at the top of a window
ToggleSizeIcon		- toggle size icon at the top right of a window
ScrollUpArrow		- scroll up arrow
VerticalScrollBar	- vertical scroll bar
ScrollDownArrow		- scroll down arrow
AdjustSizeIcon		- adjust size icon at the bottom right of a window
ScrollLeftArrow		- scroll left arrow
HorizontalScrollBar	- horizontal scroll bar
ScrollRightArrow	- scroll right arrow
OuterWindowFrame	- outer frame of the window (1 pixel wide)
IconBar			- an icon bar icon only

-select -menu -adjust -shift -ctrl -alt are the conditions in which the
filter executes. The button named must be down for the command to execute.
They may be used in any combination and are exclusive (ie -shift -adjust will
only execute if SHIFT and ADJUST are pressed and not if SHIFT ALT ADJUST are
pressed ).

-remove removes a filter from director's memory and stops it executing.

Examples (these have been split over lines for readability but should be
entered on one line)

	DirectorFilter "Title Bar Directory" * Path: -icon TitleBar -menu
		This filter makes a directory menu when you press menu over
		the title bar of any window.
	DirectorFilter "Alt Menu Directory" Filer Path: -menu -alt
		This filter makes a directory menu when you press ALT MENU
		over a filer window
	DirectorFilter "Pinboard" Pinboard Pinboard -icon WorkArea -menu
		This opens a menu called pinboard when menu is pressed over
		the work area of the pinboard. If you press menu over an
		icon on the pinboard then you will get the pinboard menu.
	DirectorFilter "Close Icon" *
		"Dynamic:DirectorObey Director:Menus.System.Close"
		-icon CloseIcon -menu
		This makes a menu appear when you press menu over any close
		box. The menu is a dynamic menu because it adjusts itself to
		the window it was used over using Director$Window and
		Director$Icon.
	DirectorFilter "Display Manager Adjust" "Display Manager" "Mode"
		-icon IconBar -adjust
		This adds an extra menu to the display manager icon bar icon
		when it is clicked with adjust.
	DirectorFilter "Task Manager Adjust" "Task Manager"
		"Dynamic:DirectorObey Director:Menus.System.Time"
		-icon IconBar -adjust
		This shows the time when adjust is clicked over the switcher
		icon

You may attach the original action of the filtered object by including
OldMenu: as an option in the filter menu.


  Other Commands
==================

	Syntax: *DirectorObey <file> [-verbose]

This command is equivalent to *Obey except it searches for Director *commands
with high priority. Obey is quite slow when processing lots of commands so
this speeds up loading a file with lots of Director commands in it.
DirectorObey cut the loading time of a 14k menu from 5.2 seconds (with Obey)
to 0.75 seconds, ie a speed up of nearly 7 times!

It should be exactly equivalent to Obey, excepting the fact that it doesn't
substitute arguments (eg %0 and %%). This means you have to be a bit careful
with %'s if you want your menus to work with Obey and DirectorObey. (See the
Icons section about -time for an example.) The -verbose or -v option is
useful for debugging.

DirectorObey will also throwback errors if you have the DDEUtils module
loded. Any errors produced will have the file name and line number of the
error embedded in them to aid debugging.


	Syntax: *MenuProcessing <On|Off|1|0|Yes|No>

This stops and restarts the processing of Menu, EndMenu, Option, Command and
Dash (ie all the menu commands). This is so that you can comment out bits of
your menus. For example if the machine you are running the menu on has no
SCSI card installed then there is no point having the SCSI menus installed
and you could check for this at menu load time.


	Syntax: *DirectorDo <command>

This GSTrans the command line and then runs it. This is useful for commands
such as Filer_Run which don't GSTrans their input, but you want to give a
string with a system variable in it. You can also run a command from a
system variable with this command.


	Syntax: *ProcessKeys [[][^]<key>|"<string>"]^

This sends the parameters to the current input focus, or hot key grabber. It
should work outside the Wimp, provided the keys are mapped as in the Wimp.
It takes a space separated list of either strings to be put into the keyboard
buffer or key descriptions (see Keys section). You can of course map these
onto keys for hot key actions. For example


	ProcessKeys "Modules" Return
	ProcessKeys F6 ^Left Down F6 ^Up ^V
	ProcessKeys "Show Obey$Dir" ^M
	ProcessKeys "42 Solution Road" ^M "Toytown" ^M "Shireshire" ^M
	ProcessKeys TAB "Option -path "

A chars menu could be provided using this, or a menu of frequently used
commands for command based application.


	Syntax: *DirectorEdit <file> [-f | -force] [-q | -quiet]

This loads the file given into an text editor (if one is loaded). It is
useful for transferring files that are not type Text to an editor.

If you supply the force (f) switch then Director will load a text editor
first, if one isn't loaded.

If you sypply the quiet (q) switch then Director won't complain if it couldn't
load the file.


	Syntax: *DirectorParsePath <path>

This parses the path supplied into 3 system variables Director$CurrentPath
Director$Leaf and Director$Dir. This is the routine that is used internally
by Director to set these variables and can occasionally be useful externally.


	Syntax: *DirectorMouseDir <var_name> [-file]

This sets the supplied system variable to the path of the window the pointer
is over. This is used to set the current directory from a key in the default
menu. It also works over Edit or Zap windows and will return the directory
that the file is in. If the pointer is not over a window with a valid path
in the title then the system variable will be set to the null string ("").

If -file is specified then the system variable may be set to point to a file
(if over an Edit or Zap window for example), otherwise it will be set to the
directory in which the file resides.


	Syntax: *DirectorSortMenu <menu> [<from> [<to>]]

This sorts the menu named alphabetically (ignoring case) by option text.
From and to are numeric parameters indicating option numbers (starting at 0)
if you only want to sort part of a menu. Don't sort menus with key short
cuts!


	Syntax: *DirectorURL <url> [<-q | -quiet>] [<-f | -force>] 

This tries to open a URL in whatever application supports the supplied URL.
If loaded it will try to use the AcornURI module to launch the URL. If that
fails or the module isn't loaded then it will use the ANT/InetSuite protocol
to try to launch the URL. If that fails then it will look for the system
variable 'Alias$URLOpen_<protocol>', where <protocol> is the likes of http and
mailto. 

If you supply the force (f) switch then Director will try to load a suitable
program.

If you sypply the quiet (q) switch then Director won't complain if it couldn't
launch the URL.


  External Interface
======================

If you Broadcast the following UserMessage

0	Total length of message rounded up to nearest 4
12	0
16	&4A100
20	X Co-ord
24	Y Co-ord
28	Mouse button state
32	Window handle
36	Icon number
40	Null terminated menu name (or extended menu)

Director will display the menu (or run the command etc) at the position
specified.

Note bytes 20-39 are as returned from Wimp_GetPointerInfo.


  SWIs
========

&4A100	Director_Menu
&4A101	Director_EndMenu
&4A102	Director_Option
&4A103	Director_Dash
&4A104	Director_Command

	Entry
		r0 = pointer to the command line for the equivalent *command
	Exit

These are defined because processing star commands is very slow and in
dynamic menus especially it is important that items can be added to menus
quickly.

&4A105	Director_Enumerate

	This enumerates lists held by director

	Entry
		r0 = pointer to block or to start
			0 = stored menus
			1 = displayed menus
			2 = icons
			3 = filters
			4 = windows
	Exit
		r0 = new pointer to block (0 for end)
		r1 = pointer to name of block

Dynamic menus to view these lists and act on them can be found on Director's
main menu.

&4A106	Director_Memory

	This returns the memory used by director

	Entry
	Exit
		r0	module size (constant)
		r1	main workspace size (constant)
		r2	total size of all allocated blocks
		r3	number of blocks allocated
		r4	dynamic area size (0 for no dynamic area)
		r5	bytes free in dynamic area
		r6	largest block in dynamic area

A dynamic menu to display this information can be found on Director's main
menu

&4A107	Director_QuickSort

	This sorts an array
	
	Entry
		r0 = pointer to start of array to sort
		r1 = pointer to end item of array (inclusive)
		r2 = size of an object
		r3 = pointer to comparison routine for the objects
			Entry
				r0 = pointer to object1
				r1 = pointer to object2
			Exit
				Comparison of object1 and object2 in flags
	Exit
		Sorted array

&4A108	Director_SortMenu

	This sorts a menu
	Don't try sorting menu blocks with keys
	
	Entry
		r0 = pointer to menu name
		r1 = number of start option (or 0 for start)
		r2 = number of end option (inclusive) (or large for end)
	Exit
		Sorted menu

  Debugging your Menus
========================

If you are having trouble with your menus when you load them (they give a
funny error and you don't know why) try opening a TaskWindow (CTRL-F12) type
in "DirectorObey -v " and SHIFT drag your menu file to the window. This will
print out commands as they are executed and you should be able to spot
exactly when it goes wrong.

	Option "Debug"
		Command TaskWindow "DirectorObey -v Director:Menus.Menu"

Would put this on a Director menu for you! (Substitute the correct name and
path of your Menu.)

Another thing to bear in mind is that if you reference a menu that you
haven't created eg

	Option "Hello" -sub "NotThere"

Where menu "NotThere" hasn't been created, this will not produce an error at
load time, and at run time it will just fail to produce the menu (not
producing an error either). Originally it produced an error, but this proved
very annoying in other circumstances (eg when you haven't defined a Pinboard
menu because you don't want one).

You may refer to one menu more than once in a menu tree, however menus can
only be on the screen once so if you tried to open a SubMenu of a Menu that
was already displayed then nothing would happen. However if you clicked on
the Option (provided it had no Command attached) it would then open the Menu
referred to.


  Utils
=========

There are a few utilities provided with Director to make Commands more
powerful and to make your life easier.

	ExpandMenu	For converting old Pinboard+ menus to Director form
	RunFilerAc	For starting off Filer_Action tasks (see examples)
	SwiModule	To be able to issue SWIs from the command line
	IfPodule	For finding out whether a podule is installed
	IfThereIs	For finding out whether a file/directory exists
	DriveName	For discovering the name of a drive from a path

You'll find these in the Utils directory within Director. See there for
further documentation.

The SWI Module is very useful for building interesting commands but is not
essential to the operation of Director so you can stop it being loaded by
default by commenting out that line in the !Run file if you desire.


  Contacts
============

The current Director website is:
	http://director.sourceforge.net


There are two current mailing lists for Director and Director related
information.

The current developers can be contacted at:
	director-developers@lists.sourceforge.net
Please report any bugs in Director to this e-mail address.

A user mailing list is available at:
	director-users@lists.sourceforge.net

To subscribe to either of these two lists send an e-mail to:
	<list-name>-request@lists.sourceforge.net
with the body:
	subscribe
You will be sent a confirmation e-mail which you need to reply to in order to
subscribe to that list.


Any bug reports, ideas or donations gratefully received.

